home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / BARNET / ACORNET / ACORN-STACK / ACRNETA021 / !AcornetA_Apps_!FreeTerm_!Help < prev    next >
Encoding:
Text File  |  1997-06-26  |  18.9 KB  |  538 lines
  1.  
  2.  
  3.                     The FreeTerm Terminal Emulator
  4.  
  5.                                Freeware
  6.              (C) Tony Howat & Merlin Hughes 1995, 1996, 1997
  7.  
  8.  
  9. 0. Copyright
  10.  
  11.   The FreeTerm application is (C) Tony Howat 1995->7, with the SICKTerm
  12.   terminal library (C) Merlin Hughes, but is released as freeware.
  13.   This means that you may copy and distribute it, subject to certain
  14.   conditions.
  15.  
  16.   Specifically, as an individual, you may only charge to cover the cost
  17.   of distributing it, and you may not use it to make money directly or
  18.   indirectly (by using it as an incentive to buy something else for
  19.   example).
  20.  
  21.   Any company which wishes to include the program on a magazine disc or
  22.   disc which will be sold *must* contact us to discuss arrangements.
  23.  
  24.   It is also imperative that anyone considering including FreeTerm in a
  25.   internet suite of any sort (free or otherwise) contacts me (Tony Howat).
  26.  
  27.   Contact Tony Howat if you are unsure of how these terms affect you.
  28.  
  29.   FreeTerm should only be distributed with the whole contents of the
  30.   original archive, with all files unmodified.
  31.  
  32.   SICKTerm makes use of ZapRedraw, (C) Dominic Symes 1994.
  33.   The project was started by Tom Hughes, author of FreeNet.
  34.  
  35.   None of the authors accept any responsibility for any
  36.   loss/damage/whatever resulting from the use of FreeTerm. It is
  37.   supplied "as is".
  38.  
  39. 1. Contents
  40.  
  41.   0.    ... Copyright
  42.   1.    ... Contents
  43.   2.    ... Introduction
  44.   3.    ... Basic use of FreeTerm
  45.   3.1   ... Downloading and Uploading text
  46.   3.2   ... Disconnection
  47.   3.3   ... Using finger
  48.   3.4   ... The Host and Port Menus
  49.   3.5   ... The FreeScript language
  50.   3.5.1 ... Points to note
  51.   3.5.2 ... Adding Scripts to the Hotlist
  52.   3.6   ... CLI options
  53.   3.7   ... The AutoRun Directory
  54.   4.    ... Miscellaneous notes
  55.   4.1   ... StrongARM Compatibility
  56.   4.2   ... Programmers' guff
  57.   4.3   ... Internationalisation
  58.   4.4   ... TtylinkD
  59.   5.    ... Contacting the authors
  60.  
  61. 2. Introduction
  62.  
  63.   The FreeTerm application is a terminal emulator for use with any
  64.   TCP/IP stack that supports the Acorn sockets interface. Currently
  65.   that means either the Acorn TCP/IP stack, FreeNet or any of the
  66.   commercial suites except Termite.
  67.  
  68.   Currently the application provides support for straightforward
  69.   telnet and finger, and display sessions in a window which emulates
  70.   a VT102 or VT52 series terminal. However, according to the beta
  71.   testers it performs these basic functions rather well, and reliably,
  72.   which is what matters.
  73.  
  74. 3. Using FreeTerm
  75.  
  76.   Starting FreeTerm places an icon on the iconbar, and clicking on
  77.   this provides a dialogue box with two writeable icons. The first
  78.   of these takes the host name (or IP address), and the second
  79.   the port number (or service name). Leaving the port
  80.   number blank will cause it to default to the standard telnet
  81.   port. Both the host and port writable icons are accompanied by
  82.   pop up menus, and there is also a hot list on the icon bar
  83.   menu. See the section 4 of this manual for details on how to set
  84.   up these menus.
  85.  
  86.   Selecting certain ports (in this current version this will only
  87.   occur with "finger") will cause the dialogue box to expand and
  88.   display and extra arguments field for extra parameters needed
  89.   to establish a certain kind of connection.
  90.  
  91.   Clicking on the connect button causes FreeTerm to establish a
  92.   connection to the specified address, and then open a terminal
  93.   window for the connection. For connections to the default telnet
  94.   port, this window will default to character mode (where each
  95.   character you type is transmitted straight away) if that is
  96.   acceptable to the remote host, otherwise line mode is used.
  97.  
  98. 3.1. Downloading and Uploading text.
  99.  
  100.   To send a file down the telnet connection drag it to the window. To
  101.   save text from a telnet window highlight it, and drag it to a filer
  102.   window.
  103.  
  104.   To download long chunks of text it is best to use the spooler, use
  105.   the "Spool>Open" save as dialogue to locate your spoolfile and
  106.   start recording. The spool may be paused, and selecting the
  107.   "Spool>Strip" option will filter control codes from the output.
  108.   When you have finished spooling click "Spool>Close"
  109.  
  110.   NB : FreeTerm only handles text downloads and uploads, ZModem
  111.        transfers may be implemented in the future.
  112.  
  113. 3.2. Disconnection
  114.  
  115.   Closing a terminal window will result in the connection to the
  116.   remote host being dropped, whilst the remote host dropping an open
  117.   connection will result in a message in the terminal window.
  118.  
  119. 3.3. Using finger
  120.  
  121.   Finger is an internet service for finding out who is using a system,
  122.   or finding out about users on a system. FreeTerm includes a finger
  123.   client. To use it enter a hostname in the normal way and select
  124.   "Finger" as the port, the connect window will grow an extra
  125.   writeable icon, this is where you enter the finger string.
  126.  
  127.   The finger string specifies what information you want from the
  128.   remote system. The most common types of finger strings are
  129.   listed below.
  130.  
  131.   <Blank>  - An empty finger string lists all the users on a system.
  132.   user     - Entering a valid username returns information on a
  133.              specific user.
  134.  
  135.   ...you can use the @ character to finger via the system you are
  136.   connecting to. So :
  137.  
  138.   @wibble.com     - lists the users on wibble.com via the system you
  139.                     actually connected to.
  140.   jack@wibble.com - gets information on the user 'jack' on wibble.com
  141.                     via the system you actually connected to.
  142.  
  143.   You can use as many @'s as you need, but at most you should only
  144.   need one if you ever need to finger through a firewall. 
  145.  
  146.   For more information on finger see RFC1288.
  147.  
  148. 3.4. The host and port menus
  149.  
  150.   The connection dialogue features two writeable icons for entering
  151.   the port name/number and the host you wish to connect to. Hostnames
  152.   are usually fairly long, and on a local network with only a few
  153.   hosts typing the same thing each time you wish to connect to a host
  154.   soon becomes tiresome. FreeTerm v0.12 and later solve this by way
  155.   of pop up menus, which are triggered by a button alongside each
  156.   writeable icon. The host menu lists entries in the format :
  157.  
  158.   foo.bar.co.uk (Telnet)
  159.   moo.cow.com (Finger)
  160.   wibble.zonk.org
  161.   ...
  162.  
  163.   The port name in brackets is the default port, not all entries may
  164.   have a default port. Clicking on an entry in the menu fills in the
  165.   writable fields in the connection box with the hostname and portname
  166.   (if present), leaving you to press the "Connect" button.
  167.  
  168.   The icon bar hot list is exactly the same as the host menu, except
  169.   that if you click on an entry with both a default port and host name
  170.   the connection starts immediately. If the entry has no default port
  171.   the connect dialogue box is displayed for you to enter a portname.
  172.  
  173.   The port menu simply lists frequently used portnames, clicking on an
  174.   entry in the menu copies the portname to the writeable icon.
  175.  
  176.   The contents of the host menu/hotlist and port menu are read from
  177.   configuration files in !FreeUser.Files.FreeTerm, namely HostList
  178.   and PortList. The format of these files is explained in their
  179.   comments.
  180.  
  181.   In older versions of FreeTerm you hand edit these files, you still
  182.   can, but there is now a user interface in the configuration window
  183.   (accessable from the iconbar 'Configure' option).
  184.  
  185. 3.5. The FreeScript language
  186.  
  187.   The FreeScript language is basically designed to log you into
  188.   machines automatically. For this reason it's very basic, although
  189.   more commands and structures may be added in future.
  190.  
  191.   FreeScript files are text files of type "FScript" (&133).
  192.  
  193.   The best way to introduce their example, so here is a script I use
  194.   to log into my university account and fire up pine (a mail/news
  195.   reader) :
  196.  
  197.   # log into loki and start pine
  198.  
  199.   session telnet loki.brunel.ac.uk
  200.     waitfor "ogin:"
  201.     sendl   "cs96arh"
  202.     waitfor "word:"
  203.     sendl   "password"
  204.     waitfor "loki%"
  205.     sendl   "pine"
  206.   sessionend
  207.  
  208.   Saving that as a file of type &133 and double clicking it will start
  209.   FreeTerm and start the script. Obviously the password isn't correct.
  210.  
  211.   More usefully, here's a script to connect to archie at the Imperial
  212.   college sunsite :
  213.  
  214.   # log into archie.doc.ic.ac.uk archie server
  215.  
  216.   session telnet archie.doc.ic.ac.uk
  217.     waitfor "ogin:"
  218.     sendl   "archie"
  219.   sessionend
  220.  
  221.   Ok, that should make things fairly obvious. We can start multiple
  222.   sessions in a script, so if I wanted to combine the scripts and log
  223.   into archie after logging into my uni account I could use :
  224.  
  225.   session telnet loki.brunel.ac.uk
  226.     waitfor "ogin:"
  227.     ..blah..
  228.     sendl   "pine"
  229.     session telnet archie.doc.ic.ac.uk
  230.       waitfor "ogin:"
  231.       sendl   "archie"
  232.     sessionend 
  233.   sessionend
  234.  
  235.   ...or I could use the following if I just wanted to start connecting to
  236.   archie at the same time as loki :
  237.  
  238.   session telnet loki.brunel.ac.uk
  239.     waitfor "ogin:"
  240.     ..blah..
  241.     sendl   "pine"
  242.   sessionend
  243.  
  244.   session telnet archie.doc.ic.ac.uk
  245.     waitfor "ogin:"
  246.     sendl   "archie"
  247.   sessionend
  248.  
  249.   ...you can also use finger in a similar way to telnet...
  250.   
  251.   session finger mimac-03.brunel.ac.uk root
  252.   sessionend
  253.  
  254.   A simple label jump mechanism is provided (allowing simple triggering)...
  255.  
  256.   session telnet wibble.org
  257.     label   loop
  258.     waitfor "hello"
  259.     sendl   "hello to you too!"
  260.     jump    loop
  261.   sessionend 
  262.  
  263.   ...and finally there are a couple of commands I haven't mentioned :
  264.  
  265.   send "whatever"    is the same as sendl, but it does not do a linefeed
  266.                      sequence after the string.
  267.   sendf "file"       sends file - correct linefeed sequence is
  268.                      inserted where needed.
  269.   task "command"     runs command as a wimp task            
  270.   waitforc           waits until a connection is established
  271.   waitfordisconnect  waits for a session to disconnect
  272.   title "text"       sets the window title of the terminal to "text".
  273.                      This causes an error if no window is open for that
  274.                      session.
  275.  
  276.   Like the rest of FreeTerm the script language is still in development,
  277.   and will gain more commands and programming constructs as the project
  278.   continues.
  279.  
  280. 3.5.1. Points to note
  281.  
  282.   1) Once started session..endsession blocks are independant of each
  283.      other.
  284.   2) When a script is running keyboard input is not ignored.
  285.  
  286. 3.5.2. Adding Scripts to the Hotlist
  287.  
  288.   To add a script to the hotlist simply copy it to the !FreeTerm.Scripts
  289.   directory. This will result in the filename appearing after normal
  290.   hotlist entries on the menu. You can change the name in the menu by
  291.   including an alternative on the first line of a script prefixed by #$.
  292.  
  293.   eg. (one of the standard scripts)
  294.  
  295.   #$Archie (HENSA)
  296.   #
  297.   # Log into Archie server at HENSA
  298.   # Tony Howat (xargle@eh.org)
  299.   #
  300.   
  301.   session telnet archie.hensa.ac.uk
  302.     title   "Archie at HENSA (login)"
  303.     waitfor "ogin:"
  304.     sendl   "archie"
  305.     title   "Archie at HENSA"
  306.   sessionend
  307.   
  308.   # end
  309.  
  310.  
  311. 3.6. CLI options
  312.  
  313.   -debug       Traces flow negociation to terminals as per pre-release
  314.   -port <port>
  315.   -host <host> These two options can be used to auto start a session
  316.                as soon as !FreeTerm is loaded.
  317.   -args <...>  Used to specify arguments if you have specified a port
  318.                which makes use of them (ie finger)
  319.   -nopop       No pop-up resolving messages, all problems reported via
  320.                full errors.
  321.   -vtlie       Force FreeTerm to report itself to the remote
  322.                machine as a VT100 rather than a VT102 terminal. You
  323.                shouldn't need this unless you're working with
  324.                broken systems.             
  325.  
  326. 3.7  The AutoRun Directory
  327.  
  328.   Files placed in the !FreeTerm.Config.AutoRun directory (or equivalent)
  329.   will be run automatically on starting FreeTerm. I use this feature for
  330.   auto starting my login script.
  331.  
  332. 4. Miscellaneous notes
  333.  
  334.   If your FreeTerm session to a unix shell gets munged try 'reset'. The
  335.   session should clear, and after a few <CR>'s you should get a normal
  336.   prompt.
  337.  
  338.   The auto close check box in the configuration window will make _telnet_
  339.   session windows close automatically if the remote end drops the
  340.   connection.
  341.  
  342.   The window finder (off the icon bar menu) gives you a list of terminal
  343.   windows open - click on one to bring it to the top.
  344.  
  345.   The VT100 keypad is useful on VMS systems etc. If you don't know what
  346.   it is or how to use it you probably don't need it.
  347.  
  348.   If you use screens and have problems with extra newlines when a character
  349.   on the last position on a line you should add "termcap LP" to .screenrc
  350.   Read the screens man page for further info.
  351.  
  352. 4.1. StrongARM Compatibility
  353.  
  354.   FreeTerm will not run properly on RISC OS 3.7 until the OS 3.7 patch
  355.   has been installed. It can be downloaded from ART's web site.
  356.  
  357.   FreeTerm also works on the Acorn NC, which is thrilling if you own one.
  358.  
  359. 4.2. Programmers' guff
  360.  
  361.   [note: you can launch sessions using ANTs URL protocol as of version 1.30
  362.          - probably much easier, but this method is slightly more flexible]
  363.  
  364.   To trigger a session via a WIMP message send Message_FreeTermOp (&440A6).
  365.   The data section should look as follows :
  366.  
  367.   length      type                      description
  368.   4 bytes     int                       action code == 2
  369.   8 bytes     empty
  370.   64 bytes    null terminated string    port name/number
  371.   80 bytes    null terminated string    destination address
  372.   80 bytes    null terminated string    the arguments
  373.   --------
  374.   236 = total length
  375.  
  376.   This message is acked if recieved by FreeTerm. OSLib example in C
  377.   follows :
  378.  
  379.   #include "oslib:user.wimp.h"
  380.   #include "kernel.h"
  381.   #include <string.h>
  382.   
  383.   #define Message_FreeTermOp 0x440a6
  384.     
  385.   typedef struct {
  386.     int action;              /* action code */
  387.     int spare1;
  388.     int spare2;
  389.     char port[64];
  390.     char dest[80];
  391.     char args[80];
  392.   } freeterm_openmsg;
  393.   
  394.   int main(void)
  395.   {
  396.     int    wimpver;
  397.     wimp_t mytaskhandle;
  398.     static wimp_block block;
  399.     wimp_message ms;
  400.     freeterm_openmsg *fom=(freeterm_openmsg *)&(ms.data);
  401.   
  402.     mytaskhandle = wimp_initialise(310,"FreeTerm Test",(void *)-1,&wimpver);
  403.   
  404.     ms.action=Message_FreeTermOp;
  405.     ms.my_ref=0;
  406.     ms.your_ref=1;
  407.     ms.sender=mytaskhandle;
  408.     strcpy(fom->port,"finger");
  409.     strcpy(fom->dest,"g7lzb.ampr.org");
  410.     strcpy(fom->args,"g7lzb");
  411.     fom->action=2;
  412.     ms.size=sizeof(freeterm_openmsg);
  413.     
  414.     wimp_send_message(wimp_USER_MESSAGE,&ms,0);
  415.   
  416.     xwimp_close_down(mytaskhandle);
  417.     return 0;
  418.   }
  419.  
  420.   The Config.Fonts file is in the format:
  421.     Name                               (string - to appear in menus)
  422.   then
  423.     zap b.m.                           (literal string)
  424.     <TermFonts$Dir>.BitMaps.X.10x20    (string)
  425.   or (for those who are prepared to tweak parameters for a while)
  426.     zap a.a.                           (literal string)
  427.     corpus.medium                      (RISC-OS font name)
  428.     10                                 Point size
  429.     16                                 Width of font
  430.     12                                 Height of font
  431.     0                                  X offset (usually 0)
  432.     8                                  Y offset (usually >0)
  433.   or
  434.     zap b.m. dir
  435.     <TermFonts$Dir>.BitMaps.CX         (Directory to find set of zap fonts)
  436.  
  437. 4.3. Internationalisation
  438.  
  439.   I would be extactic if people could provide me with resources for
  440.   different languages to be made available alongside the standard
  441.   FreeTerm distribution. e-mail them UUCoded to xargle@eh.org
  442.  
  443. 4.4. TtylinkD
  444.  
  445.   (this program has been delayed for ages, it's practically finished,
  446.    but I've just got to get round to it! still!)
  447.  
  448.   Ttylinkd is an extension for FreeTerm which allows users to connect to
  449.   your system and open chat sessions. It picks up ttylink (port 87)
  450.   connections to your machine and routes them through to FreeTerm
  451.   allowing you to converse directly with the remote user.
  452.   
  453.   Features :
  454.      * Can run independently of FreeTerm acting as an answering service,
  455.        optionally auto-starting FreeTerm when a connection is answered.
  456.      * Optionally alerts user of incoming connections both visually and
  457.        by playing a sound sample.
  458.      * Variable non-answer timeout.
  459.      * Fully editable connect/answer/etc messages.
  460.      * Integrates fully with FreeTerm.
  461.   
  462.   Ttylinkd will work with any Acorn BSD style TCP/IP stack, and so is
  463.   compatible with FreeNet, AcornNet, InterTalk, Voyager, ANT Internet etc.
  464.   (but *not* Termite Internet). However due to the program being a server it
  465.   is only really appropriate for use with providers which allocate static
  466.   IP addresses - so users of providers like Pipex and Argonet won't be able
  467.   to use it effectively. If you are confused about whether Ttylinkd is
  468.   suitable for your set up feel free to contact me. Ttylinkd will only run
  469.   under RISC OS 3.1 and later.
  470.  
  471.   *** ttylinkd will hopefully be released soon by 20-20 Software
  472.   *** and its release will be announced on comp.sys.acorn.announce.
  473.   *** It will be a *commercial* program costing £10 (single user) or £15
  474.   *** for a site licence. Further ordering details will be announced when
  475.   *** the program is released.
  476.  
  477. 4.5. Credits
  478.  
  479.   Programming :
  480.      Tom Hughes (tom@compton.demon.co.uk) started the project.
  481.      Tony Howat (xargle@eh.org) continued it.
  482.      Merlin Hughes (hughesm@cs.unc.edu) wrote the terminal emulator.
  483.  
  484.   Thanks to :
  485.      Dominic Symes (dominic.symes@armltd.co.uk) for ZapRedraw.
  486.      Stewart Brodie (s.n.brodie@ecs.soton.ac.uk) for help with ArcWeb.
  487.      Ben Summers for help with the ColourPicker, and those on
  488.      comp.sys.acorn.programmer for sorting me out on the occasions when
  489.      I saw fit to ask particularly dumb questions.
  490.      Graham Allen for his help in sadistic terminal emulator abuse.
  491.      Pineapple Software for allocating the FreeScript filetype so promptly. 
  492.  
  493.   ..and thanks to the beta testers for their helpful comments and
  494.     suggestions.
  495.  
  496. 5. Contacting the author(s)
  497.  
  498.   Any queries on the subject of FreeNet in general should be sent
  499.   to the original author of FreeTerm, Tom Hughes, who can be contacted by
  500.   email at freenet@compton.demon.co.uk, or by snail mail at:
  501.  
  502.       Tom Hughes
  503.       5 Lampits
  504.       Hoddesdon
  505.       Hertfordshire
  506.       EN11 8EH
  507.  
  508.   Those with basic configuration problems would be best served by the
  509.   comp.sys.acorn.networking newsgroup.
  510.  
  511.   Development of FreeTerm is being undertaken by Tony Howat, so
  512.   suggestions for enhancements and bug reports should be sent to him
  513.   by email to xargle@eh.org, or by snail mail at:
  514.  
  515.       Tony Howat
  516.       12 Dover Road
  517.       Birkdale
  518.       Southport
  519.       Merseyside
  520.       PR8 4SY
  521.  
  522.   (mail will be forwarded to my university address during term time)
  523.  
  524.   Only FreeTerm _specific_ queries should be sent to this address, I
  525.   can't help on a more general level. My setup is uniquely strange and
  526.   flakey :)
  527.  
  528.   If you are so enamoured with FreeTerm that you feel that you may like
  529.   to buy the authors a pint or three money is welcome at the above
  530.   address, it will be split fairly. (We're both impoverished students,
  531.   and so couldn't miss the chance of a beer or two for our trouble!)
  532.  
  533.   FreeTerm has a web page which should now available from the
  534.   20-20 Software home page. Point your browser at
  535.   http://www.xargle.demon.co.uk/2020
  536.  
  537.  
  538.